Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / asmwiz10.arc / ASMWIZ.DOC next >

Wrap

Text File | 1990-04-06 | 25.5 KB | 626 lines

The Assembly Wizard's Library ASMWIZ Copyright (c) 1990 Thomas G. Hanlin III This is ASMWIZ, a library of assembly language routines for assembly language programmers. It is copyrighted and may be distributed only under the following conditions: 1) No fee of over $5.00 may be charged for distribution. This restriction applies only to physical copies and is not meant to prevent distribution by telecommunication. 2) All ASMWIZ files must be distributed together in original, unaltered form. This includes ASMWIZ.DOC, ASMWIZ.MAN, ASMWIZ.NEW, ASMWIZ.XRF, CREATE.BAT, EXAMPLE.ASM, EXAMPLE.COM, FILES.LST, and REGISTER.TXT. You use this library at your own risk. It has been tested by me on my own computer, but I will not assume any responsibility for any problems which ASMWIZ may cause you. If you do encounter a problem, please let me know about it, and I will do my best to verify and repair the error. It is expected that if you find ASMWIZ useful, you will register your copy. This entitles you to receive the latest version of ASMWIZ on a 5 1/4" disk, complete with full source code. The source code is designed for the OPTASM assembler by SLR Systems and may require minor modifications to assemble under MASM or TASM. See REGISTER.TXT for more information. *** Limited-time Offer *** Those who register ASMWIZ before May 1, 1990, will receive a free upgrade to the next version of ASMWIZ. The ASMWIZ library was designed for use with small assembly programs and is compatible with the creation of COM files. All CALLs are of the NEAR variety. If there is sufficient interest, a FAR model will also be made. For an example of how to set up your program to access the ASMWIZ library, how to LINK the routines, and so forth, see the EXAMPLE.ASM, EXAMPLE.COM, and CREATE.BAT files. Note that DOS-dependent services expect DOS 2.0 or higher versions, unless otherwise specified. Services to be added in future versions include screen save/restore, support for Hercules/CGA/EGA/VGA graphics, additional mouse handling, keyboard control and input services, flexible file handling with automatic network support and buffering, expanded and extended memory support, background music, ANSI emulation, communications, and much more. If there is something in particular that you'd like to see, please let me know about it. Base Conversion Services The Base Conversion Services provide the ability to convert back and forth between a number and its ASCIIZ representation. Any base from 2-36 may be employed, so these routines encompass binary, decimal, hex and octal conversions. Services are provided for integers and long integers, both signed and unsigned. The following services are available: BC_ASC2INT convert an ASCIIZ string to an unsigned integer BL <-- base from which to convert DS:SI <-- ptr to string ------- AX = unsigned integer BC_ASC2LONG convert an ASCIIZ string to an unsigned long integer BL <-- base from which to convert DS:SI <-- ptr to string ------- DX,AX = unsigned long integer BC_ASC2SINT convert an ASCIIZ string to a signed integer BL <-- base from which to convert DS:SI <-- ptr to string ------- AX = signed integer BC_ASC2SLONG convert an ASCIIZ string to a signed long integer BL <-- base from which to convert DS:SI <-- ptr to string ------- DX,AX = signed long integer BC_INT2ASC convert an unsigned integer to an ASCIIZ string AX <-- unsigned integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 17 bytes) BC_LONG2ASC convert an unsigned long integer to an ASCIIZ string DX,AX <-- unsigned long integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 33 bytes) BC_SINT2ASC convert a signed integer to an ASCIIZ string AX <-- signed integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 18 bytes) BC_SLONG2ASC convert a signed long integer to an ASCIIZ string DX,AX <-- signed long integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 34 bytes) Delay Services The Delay Services are for those times when you want the computer to sit around doing nothing for a while. Delays of various timing resolution are available for anything from small to large waits. Note that timers 0-1 may be used by ASMWIZ itself. See ASMWIZ.MAN for more details on the 100th-second delay services. The following services are available: MD_DELAY delay for a number of 100ths of seconds CX <-- delay (0-32767) MD_DONE terminate 100th-second delay handler MD_GETTIMER get a delay count AL <-- timer number (0-3) ------- CX = delay * 2 (0-65534) MD_INIT initialize 100th-second delay handler MD_SETTIMER set a delay count AL <-- timer number (0-3) CX <-- delay (0-32767) MD_TICK delay for a number of clock ticks (18ths of seconds) CX <-- delay (0-65535) Math (32-bit) Services The Math Services provide support for the basic arithmetic operations on unsigned long integers. They allow you to add two 32-bit integers, subtract one 32-bit integer from another, multiply two 32-bit integers (giving a 64-bit result), and divide a 63-bit integer by a 32-bit integer (giving a 32-bit result and 32-bit remainder). Since 32-bit integers are rather unwieldy unless you're using an 80386 or above (in which case you don't need these services anyway), the numbers are passed back and forth through a buffer in memory. The following services are available: MA_ADD32 add two unsigned long integers DS:SI <-- first operand DS:SI+4 <-- second operand ------- DS:SI+8 = result MA_DIV32 divide an unsigned 63-bit integer by an unsigned long integer DS:SI <-- dividend (64 bits: high bit must be zero) DS:SI+8 <-- divisor (unsigned long integer) ------- DS:SI+12 = quotient (unsigned long integer) DS:SI+16 = remainder (unsigned long integer) MA_MUL32 multiply two unsigned long integers DS:SI <-- first operand DS:SI+4 <-- second operand ------- DS:SI+8 = result (unsigned very long integer: 64 bits) MA_SUB32 subtract one unsigned long integer from another DS:SI <-- first operand DS:SI+4 <-- second operand ------- DS:SI+8 = result Memory Services The Memory Services provide low-level routines for memory manipulation. They allow you to manipulate addresses, as well as providing a "smart" block move service that automatically handles overlaps between source and destination areas. Among the address manipulation services are routines to convert an address to have the smallest possible segment and highest possible offset (or vice versa) to allow REP operations to always handle up to 65,519 bytes without wrapping within the segment. The following services are available: ME_HIGHOFS convert an address to have the lowest segment & highest offset DX:AX <-- segment:offset ------- DX:AX = converted segment:offset ME_LOWOFS convert an address to have the highest segment & lowest offset DX:AX <-- segment:offset ------- DX:AX = converted segment:offset ME_MOVE move a block of memory without overlap conflicts DS:SI <-- source segment:offset ES:DI <-- destination segment:offset CX <-- bytes to move (0 - 65,519) Miscellaneous Services The Miscellaneous Services provide a number of services for various purposes, such as parsing the command line, scanning the environment for a parameter, and generating pseudo-random numbers. They eliminate much of the tedium of these common chores. The following services are available: MI_BOOT reboot the computer (warm boot) MI_MATCHFILE see if a filename matches a specified pattern DS:SI <-- pattern (may contain wildcards) ES:DI <-- filename (may not contain drive or path specs) ------- flags = ZF if the filename matches the pattern NZ if the filename doesn't match the pattern MI_PARSE parse a command line into filespecs and options DS:SI <-- ptr to command line (for COM files, is CS:0080h) ES:DI <-- ptr to filename buffer (recommend 128 bytes) ES:BX <-- ptr to option buffer (recommend 128 bytes) AL <-- switch character (normally "/" for MS-DOS) ------- AH = number of options AL = number of filenames MI_RANDOM generate a pseudo-random number DX <-- random number range (1-4000) ------- AX = random number (0 to DX - 1) MI_RANDOMIZE initialize the pseudo-random number generator AX <-- random number seed (use 0FFFFh for auto-seeding) MI_SCANENV scan the DOS environment for a parameter DS:SI <-- ptr to the DOS environment or similar table ES:DI <-- ptr to the parm for which to search ------- CY if not found NC if match found; DS:SI points to parm value Mouse Services The Mouse Services provide a simple set of functions for dealing with Microsoft-compatible mouse devices. You may see if a mouse exists, control the mouse cursor, and get information about the mouse buttons. The following services are available: MO_HIDECURSOR hide the mouse cursor MO_INIT see if a mouse is installed (and if so, how many buttons) ------- AL = number of buttons on the mouse (zero if no mouse) MO_LOCATE set the mouse cursor location DH <-- row (1-25) DL <-- column (1-80) MO_RANGE set the mouse cursor range CH <-- top row (1-25) CL <-- leftmost column (1-80) DH <-- bottom row (1-25) DL <-- rightmost column (1-80) MO_SHOWCURSOR show the mouse cursor MO_WHERE get the mouse cursor location and button states ------- AL = left button (0 = not pressed, 1 = pressed) AH = right button (0 = not pressed, 1 = pressed) DH = row (1-25) DL = column (1-80) Sound and Music Services The Sound and Music Services provide the ability to generate sound effects and music. The current service is rather on the primitive side. It will be supplemented by a background (interrupt-driven) music command language in a future version of ASMWIZ. The following services are available: MU_SOUND produce a sound of a specified duration and frequency AX <-- frequency (Hertz; about 50-4000 is useful) DX <-- duration (18ths of seconds) Video Text Services Displaying text is something that almost every program will do. The ASMWIZ library contains numerous sets of video services which make it easy to use the display in a consistent manner. The display services are divided into four sets of routines, each of which provides similar capabilities: DOS-level services BIOS-level services Machine-level services for text modes Machine-level services for CGA graphics modes The DOS services provide the maximum level of compatibility. They are also the slowest of the video services and the least flexible. The main practical advantage of using DOS services is that they allow redirection, so the output of your program can be sent to a file, a printer, or a serial port as well as to the display. Since DOS itself has only minimal video support, you will need to make sure an ANSI driver is installed before using these services. See your DOS manual on ANSI.SYS for more information if you need it. The BIOS services provide a very good level of compatibility. They are faster and more flexible than the DOS services. Like the DOS services, these routines are quite likely to work on nonstandard displays. The machine-level services are the least compatible. They will work on any standard PC clone, but not on semi-compatible hardware or with nonstandard display devices. In return for this disadvantage, these services are much faster than the other services and provide a great deal more flexibility. Text Display Speeds Speed tests were conducted on an 8088 machine with a Phoenix BIOS, running MS-DOS 3.30. Ratings may vary on other machines and DOS versions. The tests were conducted on how quickly strings could be printed to the display. Speeds are listed relative to the slowest display method (DOS services). +-----------+-----------+-----------+ | DV_STROUT | BV_STROUT | MV_STROUT | +------------+-----------+-----------+-----------+ | Mode 3 | | | | | text mode | 100% | 162% | 572% | +------------+-----------+-----------+-----------+ | Mode 4 | | | | | CGA lo-res | 100% | 114% | 180% | +------------+-----------+-----------+-----------+ | Mode 6 | | | | | CGA hi-res | 100% | 122% | 204% | +------------+-----------+-----------+-----------+ From this chart, you can see that using BIOS display services is 14% - 62% faster than using DOS services. Using machine-level services is 80% - 472% faster than using DOS services, and about 60% - 250% faster than using BIOS services. If system compatibility is a major concern, then note that the DOS services are most compatible, followed by the BIOS services and then the machine-level services. The price you pay for compatibility is speed and flexibility. The machine-level services are the fastest and most flexible, followed by the BIOS services and then the DOS services. General Video Information For all text routines, color/attributes are encoded as a single byte value: bit: 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | B | backgnd | I | foregnd | +---+---+---+---+---+---+---+---+ B: "blink". Set if the color is blinking. I: "intense". Set if the foreground color is intense (bright or light). backgnd, foregnd: the actual foreground and background colors. The bits specify the red, green, and blue components of the color, giving the following list of colors: 0 black (if intense, may or may not be displayed as gray) 1 blue 2 green 3 cyan 4 red 5 magenta 6 brown (if intense, is usually displayed as yellow) 7 white Text in CGA graphics modes is different. If you use BIOS or DOS services, you may only specify a foreground color, which may be 0-3. If you use the CGA machine-level services, you may specify a background color as well as a foreground color. Color encoding is the same as for text mode, with the exception that there are no "blinking" or "intense" bits, and the color range is 0-3 instead of 0-7. The 0-3 range does not follow the above color list; the colors depend instead on which CGA palette is in use. Screen modes are specified as a single byte, as follows: Mode Resolu. Type Colr Use Adapter(s) Services 0 40x25 b&w 16 text CGA, EGA, VGA MV, BV, DV 1 40x25 color 16 text CGA, EGA, VGA MV, BV, DV 2 80x25 b&w 16 text CGA, EGA, VGA MV, BV, DV def- 3 80x25 color 16 text CGA, EGA, VGA MV, BV, DV 4 320x200 color 4 graphics CGA, EGA, VGA CG, BV, DV 5 320x200 b&w 4 graphics CGA, EGA, VGA CG, BV, DV 6 640x200 color 2 graphics CGA, EGA, VGA CG, BV, DV mda- 7 80x25 b&w - text MDA, EGA, VGA BV 13 320x200 color 16 graphics EGA, VGA BV 14 640x200 color 16 graphics EGA, VGA BV 15 640x350 mono - graphics EGA, VGA BV 16 640x350 color 16 graphics EGA, VGA BV 17 640x480 color 2 graphics VGA BV 18 640x480 color 16 graphics VGA BV 19 320x200 color 256 graphics VGA BV BV = BIOS video services DV = DOS video services MV = Machine-level text services CG = Machine-level CGA graphics services Video Service List All of the video services share a common nomenclature and calling procedure. For many of the services, you will have a choice of whether to use DOS, BIOS, Machine-level (text modes), or Machine-level (CGA graphics modes). The level is specified as a two-letter code prefix to the routine name, where the codes are as follows: DV DOS Video BV BIOS Video MV Machine-level (text mode) Video CG Machine-level (CGA graphics mode) Video The routine to display a string using DOS services, for example, is named DV_STROUT (DOS Video service, String Output). It usually isn't a good idea to "mix and match" video services of different types. The following services are available: CHROUT display a character BV,DV,MV,CG AL <-- character CLS clear the screen and home the cursor BV,DV,MV,CG COLOR set the text color BV,DV,MV,CG AL <-- color/attribute CRLF display a carriage return and a linefeed BV,DV,MV,CG CLEOLN clear from the cursor to the end of the line BV,DV,MV,CG DELCHR delete the character at the cursor , ,MV, DELLINE delete the current line BV,dv,MV, GETCOLOR get the text color BV, ,MV,CG AL = color/attribute HIDECURSOR hide the cursor BV, ,MV, INIT initialize the video service routines MV,CG INSCHR insert a space at the cursor , ,MV, INSLINE insert a row at the current line BV,dv,MV, LOCATE set the cursor position BV,DV,MV,CG DH <-- row (1-25), DL <-- column (1-40/80) MODE set the screen mode BV,DV,MV,CG AL <-- mode (see General Video Information) POPUP display a pop-up window BV, ,MV, DX <-- parameter pointer SHOWCURSOR show the cursor BV, ,MV, STROUT display a string BV,DV,MV,CG DS:DX <-- pointer to ASCIIZ string WHERE get the current cursor position BV, MV,CG DH = row (1-25), DL = column (1-40/80) String Services (ASCIIZ) The ASCIIZ String Services provide a wide assortment of services for dealing with null-terminated strings. Note that, although many of the string services are designed to place the result of processing a first string into a second string, it is not actually necessary to use two string buffers. The services are designed so that you can place the results back into the original string buffer by using the same address for both strings. The following routines are included amongst the ASCIIZ String Services: S0_COMPARE compares two strings DS:SI <-- first string ES:DI <-- second string Flags = ZF if equal, NZ if not equal CY if first < second, NC if first >= second S0_DUPE forms a string by duplicating a character ES:DI <-- result string AL <-- character to duplicate CX <-- number of times to repeat the character S0_LEFT copies a specified section from the left of a string DS:SI <-- source string CX <-- number of characters to copy ES:DI <-- result string S0_LENGTH gets the length of a string (excluding the null terminator) DS:SI <-- string CX = string length S0_LOCASE converts a string to lowercase (international) DS:SI <-- source string ES:DI <-- result string S0_MID copies a specified section of a string DS:SI <-- source string DX <-- where to start copying from (1-xx) CX <-- how many characters to copy ES:DI <-- result string S0_RIGHT copies a specified section from the right of a string DS:SI <-- source string CX <-- number of characters to copy ES:DI <-- result string S0_TRIM trims the "white space" (blanks and control characters) from either side (or both sides) of a string DS:SI <-- source string AL <-- set bit 0 to trim the left, bit 1 for right ES:DI <-- result string S0_UPCASE converts a string to uppercase (international) DS:SI <-- source string ES:DI <-- result string Telecommunications Services The Telecommunications Services provide functions that are useful for telecommunications. This includes services for manipulating the serial port and services that aid in performing file transfers and similar functions. The following routines are included amongst the Telecommunications Services: TC_CHKSUM calculate the Xmodem/Ymodem checksum of a block of data DS:SI <-- pointer to a data block CX <-- length of data block (in bytes) ------- AX = checksum TC_CRC calculate the Xmodem/Ymodem CRC of a block of data DS:SI <-- pointer to a data block CX <-- length of data block (in bytes) ------- AX = resulting CRC Time and Date Services The Time and Date Services provide international date handling. Based on the country code given it by DOS, these services return strings that represent the current time or date in the appropriate format for that country. These services provide a simple way to make your software work properly on any computer anywhere, across the world. See the COUNTRY entry under CONFIG.SYS in your DOS manual for more details. Note that DOS version 3.0 or greater is required to insure that the date and time delimiters are appropriate. Otherwise, the date and time formats will still be correct, but the delimiters used will be assumed to be "-" for the date and ":" for the time. With DOS versions before 3.0, the time will be presented in 12-hour (am/pm) format. The following routines are included amongst the Time and Date Services: TD_GETDATE get the current date as an ASCIIZ string DS:DX <-- pointer to a buffer (minimum 11 bytes) AL <-- 0 for 2-digit year, 1 for 4-digit year TD_GETTIME get the current date as an ASCIIZ string DS:DX <-- pointer to a buffer (minimum 8 bytes)